home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 015a / decide22.zip / DECIDE.DOC next >
Text File  |  1992-02-04  |  11KB  |  269 lines
  1. DECIDE                       .BAT file tool                FLOWtools(tm)
  2. ────────────────────────────────────────────────────────────────────────
  3.  
  4.            ┌────────────────────────────────────────────────╖
  5.            │      DECIDE -- BAT Prompter Version 2.2        ║
  6.            │   Copyright (c) 1991 by FLOW Research, Inc.    ║
  7.            │            All Rights Reserved.                ║
  8.            ╘════════════════════════════════════════════════╝
  9.  
  10. NAME
  11.          Decide -- multiple-choice branching in .BAT files
  12.  
  13.  
  14. SYNOPSIS
  15.          Decide [/optlist] [-num] [prompt]
  16.  
  17.  
  18. DESCRIPTION
  19.  
  20.  
  21.          DECIDE fills a gap in the utilities that come standard with
  22.          MS-DOS. DOS supports the automation of repetitive tasks with
  23.          "Batch" files. In their most basic form, these are text files
  24.          containing a list of valid DOS commands. By giving the file a
  25.          name with a .BAT extension, it becomes possible to use the
  26.          file as a DOS command.
  27.  
  28.          Unfortunately, there is no simple way to make batch files
  29.          interactive. Early versions of DOS had only the PAUSE command
  30.          to allow changing floppy disks. Many versions of DOS now come
  31.          with some sort of ASK utility which lets a batch file do one
  32.          thing or another based on your answer to a Yes/No question.
  33.  
  34.          DECIDE addresses two problems: first, that many questions you
  35.          would like to ask in a batch file can't be answered by Yes or
  36.          No; second, that you would sometimes like the batch file to
  37.          do something if you don't answer at all -- for instance, if
  38.          you're on the road and dialing in to your computer, or even if
  39.          you just turned it on and went for coffee.
  40.  
  41.          DECIDE works by using two poorly-documented and underutilized
  42.          features of DOS's batch-command language, to wit:
  43.  
  44.          IF ERRORLEVEL <x>        and
  45.          GOTO <label>
  46.  
  47.          The "DOS errorlevel" is a special value which programs can set
  48.          when they stop running and return you to DOS. Its original
  49.          intention was to let programs indicate some kind of error
  50.          condition. With DECIDE, you can use the DOS errorlevel to make
  51.          batch files as sophisticated as some "DOS shell" programs.
  52.  
  53.          A typical DECIDE command line in a batch file looks like this:
  54.  
  55.             DECIDE /WEF WordPerfect, Excel, FoxBase
  56.          
  57.          When DOS reaches the line in your batch file containing the
  58.          DECIDE command as shown above, the following will appear on
  59.          your screen:
  60.  
  61.                  WordPerfect, Excel, FoxBase (W/E/F)?
  62.  
  63.          You may then press one of the three indicated keys ('w', 'e'
  64.          or 'f'). Pressing ENTER is the equivalent of pressing the
  65.          first key in the list (in our example, 'w'). If you press any
  66.          other key you will see the following on your screen:
  67.  
  68.              Please choose one from the list.
  69.  
  70.                  WordPerfect, Excel, FoxBase (W/E/F)?
  71.  
  72.          When you press one of the allowable keys (or ENTER), DECIDE
  73.          quits. However, when it quits it sets the DOS error-level
  74.          value to match the key you pressed. Again using the example
  75.          above, if you pressed ENTER or W (or w) the DOS error level
  76.          would be 0. If you pressed E, it would be 1. If you pressed F,
  77.          it would be 2. The allowed keys are all specified with a
  78.          forward-slash ('/'), followed by up to 20 characters with
  79.          no intervening spaces.
  80.  
  81.          To use this error level in you batch file, you need some lines
  82.          after the DECIDE command to, well, decide what to do next.
  83.          Let's expand on the example above:
  84.  
  85.             DECIDE /WEF WordPerfect, Excel, FoxBase
  86.             if errorlevel 2 echo Do WordPerfect
  87.             if errorlevel 1 echo Do Excel
  88.             if errorlevel 0 echo Do FoxBase
  89.  
  90.          Each "if errorlevel" line tests for a value of the DOS 
  91.          errorlevel. If the DOS errorlevel is AT LEAST the value
  92.          specified in the line, DOS will do whatever is in the line
  93.          after the "if errorlevel <x>." This "at least" has to do with
  94.          the original intention of the DOS errorlevel as an error 
  95.          indicator. If you were to type the four lines above into a .BAT
  96.          file, and ran it, the result when you pressed 'e' would be
  97.  
  98.              Do Excel
  99.              Do FoxBase
  100.  
  101.          This is because DOS will interpret as true any "if 
  102.          errorlevel" statement that specifies a value EQUAL TO OR LESS
  103.          THAN the current errorlevel. See the examples for the proper
  104.          syntax of batch files using DECIDE.
  105.  
  106.          The next option in DECIDE lets you program a countdown. Let's
  107.          modify the example we've already seen:
  108.  
  109.             DECIDE /WEF -5 WordPerfect, Excel, FoxBase
  110.  
  111.          When you run this from the DOS prompt or from within a batch
  112.          file, the prompt would be:
  113.  
  114.              5   WordPerfect, Excel, FoxBase (W/E/F)?
  115.  
  116.          Unless you press a key immediately, you will see the '5'
  117.          become '4' after one second, then '3', etc. When it reaches
  118.          0, DECIDE will quit to DOS with the DOS error level set to 0.
  119.          In other words, if you press no key for five seconds, it will 
  120.          have the same effect as if you had pressed 'W' or ENTER. This
  121.          can be used to create batch files with a certain "default"
  122.          behavior, but which can behave differently if you wish at the
  123.          press of a key. You can specify a delay of up to 60 seconds.
  124.          The best way to understand this feature is to look at the 
  125.          examples.
  126.  
  127.         Here is a summary of the DECIDE command-line options.
  128.  
  129.          Options:     /(characters)       Allowed key responses
  130.                       -(number)           Delay in seconds
  131.                       (Anything else)     Part of prompt
  132.  
  133.          DECIDE with no command-line parameters will display a brief
  134.          usage message. DECIDE /V will display the program's version
  135.          number and copyright notice, then quit.
  136.  
  137.          If no text is specified for the prompt, the program will use
  138.          the message "Run" as a default. If no key-response list is
  139.          specified, it will use /YN as a default. Thus the simplest
  140.          possible DECIDE command line is simply:
  141.  
  142.             DECIDE -10
  143.  
  144.          which will produce the prompt
  145.  
  146.              Run (Y/N)?
  147.  
  148.          and countdown for 10 seconds before defaulting to response Y.
  149.  
  150.  
  151. EXAMPLES
  152.          In the examples that follow, the line "echo off" at the top
  153.          of each sample batch file prevents the commands in the rest
  154.          of the file from being displayed on the screen before DOS
  155.          runs them. Lines of the form ":label" are the standard format
  156.          for indicating the place to which a batch file "goto" command
  157.          should continue running. Refer to your DOS manual for more
  158.          information on these and other batch file commands.
  159.  
  160.          Example 1 -- batch file using DECIDE to load Windows 3.0
  161.          ───────────────────────────────────────────────────────────────
  162.          echo off
  163.          DECIDE -15 /NRSE Windows: None, Real Mode, Standard, Enhanced
  164.          if errorlevel 3 goto wenh
  165.          if errorlevel 2 goto wstd
  166.          if errorlevel 1 goto wreal
  167.          REM if we got here errorlevel is 0
  168.          goto done
  169.          :wenh
  170.          WIN /E
  171.          goto done
  172.          :wstd
  173.          WIN /S
  174.          goto done
  175.          :wreal
  176.          WIN /R
  177.          goto done
  178.         :done
  179.          REM end of batch file
  180.          ───────────────────────────────────────────────────────────────
  181.  
  182.          The effect of this batch file is to give you 15 seconds to
  183.          decide in which mode you would like to run Windows. If you
  184.          don't make up your mind in 15 seconds, or if you walk away
  185.          from your PC, the batch file will simply quit to DOS without
  186.          running Windows at all.
  187.  
  188.          Example 2 -- an AUTOEXEC.BAT file for an occasional BBS Sysop
  189.          ───────────────────────────────────────────────────────────────
  190.          echo off
  191.          REM no key-response list specified so DECIDE uses default /YN
  192.          DECIDE -50 Load BBS
  193.          if errorlevel 1 goto nobbs
  194.          REM if we got here we should load the BBS
  195.          SEADOG -REALLY -Arduous -Option -List
  196.          SET PATH=C:\TBBS;C:\TBBS\EXTRA;C:\TBBS\FILES
  197.          REM Chain to the batch file that loads the BBS software
  198.          C:
  199.          CD \TBBS
  200.          RUNBBS
  201.          REM next line is pro-forma since we never return from
  202.          REM the chain-command to RUNBBS.BAT
  203.          goto done
  204.          :nobbs
  205.          REM BBS not loaded, do non-BBS kinds of things
  206.          SET PATH=C:\NONBBS;C:\KINDSOF\THINGS;C:\GAMES
  207.          :done
  208.          ───────────────────────────────────────────────────────────────
  209.  
  210.          The above example shows a way of using DECIDE to, well, decide
  211.          which batch file you want to run.
  212.  
  213.          Example 3 -- an AUTOEXEC.BAT file for an *Infrequent* BBS Sysop
  214.          ───────────────────────────────────────────────────────────────
  215.          echo off
  216.          REM Explicitely make key-response list /NY to make N default
  217.          DECIDE -50 /NY Load BBS
  218.          if errorlevel 1 goto Loadbbs
  219.          goto nobbs
  220.          :Loadbbs
  221.          REM if we got here we should load the BBS
  222.          SEADOG -REALLY -Arduous -Option -List
  223.          SET PATH=C:\TBBS;C:\TBBS\EXTRA;C:\TBBS\FILES
  224.          REM Chain to the batch file that loads the BBS software
  225.          C:
  226.          CD \TBBS
  227.          RUNBBS
  228.          REM next line is pro-forma since we never return from
  229.          REM the chain-command to RUNBBS.BAT
  230.          goto done
  231.          :nobbs
  232.          REM BBS not loaded, do non-BBS kinds of things
  233.          SET PATH=C:\NONBBS;C:\KINDSOF\THINGS;C:\GAMES
  234.          :done
  235.          ───────────────────────────────────────────────────────────────
  236.  
  237.          This example shows how to change the default behavior when
  238.          using DECIDE's timer feature. We have only specified /NY
  239.          instead of the default /YN as our key-response list, we
  240.          have changed the meaning of pressing 'N' to set the error
  241.          level to 0 instead of 1 (as in Example 2). A little change
  242.          in the "errorlevel" test and the use of "goto" and voilà!
  243.          The batch file will NOT run the BBS if no key is pressed.
  244.  
  245.          While these examples may make DECIDE sound complicated, it is
  246.          really a very simple program, that solves a simple problem
  247.          simply. Like so many shareware utilities, it should have
  248.          been included with MS-DOS.
  249.  
  250.  
  251. NOTES
  252.          See FLOWREAD.ME for license terms, restrictions, and source
  253.          code availability.
  254.  
  255.  
  256. TECHNICAL
  257.          DECIDE traps the Ctrl-Break signal, displays an "Aborted"
  258.          message, and quits with an errorlevel of 0. It uses no
  259.          file I/O or memory allocation and has a "petite" stack,
  260.          so it should run without fail in many situations, even
  261.          after a badly-behaved program has "retouched" memory.
  262.  
  263. AUTHOR
  264.          Daniel Gross
  265.          FLOW Research, Inc.
  266.          119 Avenue D, #4
  267.          New York NY 10009
  268.  
  269.